Work Item / Issue Reference

GitHub Issue: #565

Summary

Fixes the indefinite hang of mssql_python.connect() when the target server is reached through an in-process SSH tunnel created with paramiko + sshtunnel (issue #565, originally reported as #491).

Root cause

PR #541 released the GIL around SQLDriverConnect, SQLDisconnect, and SQLEndTran, but a handful of SQLSetConnectAttr call sites in mssql_python/pybind/connection/connection.cpp were left holding the GIL:

• Connection::setAutocommit — SQL_ATTR_AUTOCOMMIT. This is the call that hangs in the issue's repro: it runs by default immediately after every connect().
• Connection::setAttribute (int / wide-string / bytes paths) — user-facing set_attr().
• Connection::reset — SQL_ATTR_RESET_CONNECTION and SQL_ATTR_TXN_ISOLATION, called by the connection pool on acquire.

When the GIL is held during a call that ends up doing blocking work, paramiko's transport thread cannot run and so cannot forward bytes through the SSH channel — the driver waits forever for a response that never comes. pyodbc does not exhibit this because it releases the GIL around its blocking ODBC calls.

Fix

Wrap each of these call sites in py::gil_scoped_release, matching the pattern PR #541 already established for SQLDriverConnect / SQLEndTran. Local-only attribute reads (SQLGetConnectAttr for SQL_ATTR_CONNECTION_DEAD / SQL_ATTR_AUTOCOMMIT, SQLGetInfo, SQLAllocHandle) are intentionally left alone.

Additional fix: Connection pool mutex/GIL deadlock

The initial GIL-release change in Connection::reset() introduced a secondary deadlock in ConnectionPool::acquire(). The pool's acquire() method called conn->isAlive() and conn->reset() while holding the pool _mutex. With reset() now releasing the GIL internally, this created a classic ABBA lock-ordering inversion:

The fix restructures ConnectionPool::acquire() to pop one candidate connection from the pool under the mutex, then validate it (isAlive() + reset()) outside the mutex. This follows the same pattern already established in the pool for connect() (Phase 2.5) and disconnect() (Phase 3/4), where blocking ODBC calls that release the GIL are performed without holding the pool lock.

Why this is safe:

1. No data races on _pool: The candidate is popped from the deque atomically under the mutex before any validation. No other thread can access the same connection object.
2. _current_size stays accurate: Stale connections are decremented during pruning (Phase 1). Failed candidates are decremented individually after validation. New connections increment the count under the mutex before connect() is called.
3. Pool size limit is respected: The "reserve a new slot" check (_current_size < _max_size) still happens under the mutex, after confirming no viable candidates remain.
4. Exception safety: If isAlive() or reset() throws, the connection is caught and treated as dead — it goes to the disconnect list and _current_size is decremented.
5. Single-threaded behavior unchanged: With one thread, the loop simply pops, validates, and returns — identical to the previous while-loop but without holding the mutex during ODBC calls.

Verification

• Reproduced Reopen Issue #491: SSH tunneling fails using paramiko+sshtunnel #565 locally with an in-process Python TCP forwarder (simulating paramiko/sshtunnel). Before the GIL-release fix, mssql_python.connect() hung indefinitely; after the fix it completes in ~0.3s.
• The pool deadlock was reproduced by returning connections to the pool and having 2+ threads call connect() concurrently — this hung indefinitely before the pool fix and completes instantly after.
• Full test suite: 1707 passed, 64 skipped, 0 failures (~2 minutes).

Diff: 2 files changed — connection.cpp (+42/-12 GIL release) and connection_pool.cpp (+39/-26 mutex restructure).